import {Layout} from '../../src/Layout';
export default Layout;

import docs from 'docs:react-aria-components';
import toastDocs from 'docs:./ExampleToast';
import '../../tailwind/tailwind.css';
import Anatomy from '@react-aria/toast/docs/toast-anatomy.svg';
import {InlineAlert, Heading, Content} from '@react-spectrum/s2';

export const tags = ['notifications'];
export const version = 'alpha';
export const relatedPages = [{'title': 'useToast', 'url': 'Toast/useToast.html'}];
export const description = 'Displays brief, temporary notifications of actions, errors, or other events in an application.';

# Toast

<PageDescription>{docs.exports.UNSTABLE_Toast.description}</PageDescription>

<ExampleSwitcher>
  ```tsx render docs={toastDocs.exports.MyToast} links={toastDocs.links} props={['title', 'description', 'timeout']} initialProps={{title: 'Files uploaded', description: '3 files uploaded successfully.', timeout: 0}} type="vanilla" files={["starters/docs/src/Toast.tsx", "starters/docs/src/Toast.css"]}
  "use client";
  import {MyToastRegion, queue} from 'vanilla-starter/Toast';
  import {Button} from 'vanilla-starter/Button';

  function Example(props) {
    return (
      <div>
        <MyToastRegion />
        <Button onPress={() => queue.add(
          {
            title: props.title || 'Files uploaded',
            description: props.description || '3 files uploaded successfully.'
          },
          props.timeout ? {timeout: props.timeout} : undefined
        )}>
          Show Toast
        </Button>
      </div>
    );
  }
  ```

  ```tsx render docs={toastDocs.exports.MyToast} links={toastDocs.links} props={['title', 'description', 'timeout']} initialProps={{title: 'Files uploaded', description: '3 files uploaded successfully.', timeout: 0}}  type="tailwind" files={["starters/tailwind/src/Toast.tsx"]}
  "use client";
  import {MyToastRegion, queue} from 'tailwind-starter/Toast';
  import {Button} from 'tailwind-starter/Button';

  function Example(props) {
    return (
      <div>
        <MyToastRegion />
        <Button onPress={() => queue.add(
          {
            title: props.title || 'Files uploaded',
            description: props.description || '3 files uploaded successfully.'
          },
          props.timeout ? {timeout: props.timeout} : undefined
        )}>
          Show Toast
        </Button>
      </div>
    );
  }
  ```

</ExampleSwitcher>

## Content

### Title and description

Use the `"title"` and `"description"` slots within `<ToastContent>` to provide structured content for the toast. The title is required, and description is optional.

<ExampleSwitcher>
  ```tsx render hideImports type="vanilla"
  "use client";
  import {queue} from 'vanilla-starter/Toast';
  import {Button} from 'vanilla-starter/Button';

  function Example() {
    return (
      <Button
        ///- begin highlight -///
        onPress={() => queue.add({
          title: 'Update available',
          description: 'A new version is ready to install.'
        })}
        ///- end highlight -///
      >
        Check for updates
      </Button>
    );
  }
  ```

  ```tsx render hideImports type="tailwind"
  "use client";
  import {queue} from 'tailwind-starter/Toast';
  import {Button} from 'tailwind-starter/Button';

  function Example() {
    return (
      <Button
        ///- begin highlight -///
        onPress={() => queue.add({
          title: 'Update available',
          description: 'A new version is ready to install.'
        })}
        ///- end highlight -///
      >
        Check for updates
      </Button>
    );
  }
  ```

</ExampleSwitcher>

### Close button

Include a `<Button slot="close">` to allow users to dismiss the toast manually. This is important for accessibility.

<InlineAlert variant="notice">
  <Heading>Accessibility</Heading>
  <Content>We recommend that that the close button should be rendered as a sibling of `<ToastContent>` rather than inside it, so that screen readers announce the toast content without the close button first.</Content>
</InlineAlert>

## Dismissal

Use the `timeout` option to automatically dismiss toasts after a period of time. For accessibility, toasts should have a minimum timeout of **5 seconds**. Timers automatically pause when the user focuses or hovers over a toast.

<ExampleSwitcher>
  ```tsx render hideImports type="vanilla"
  "use client";
  import {queue} from 'vanilla-starter/Toast';
  import {Button} from 'vanilla-starter/Button';

  function Example() {
    return (
      <Button
        ///- begin highlight -///
        onPress={() => queue.add(
          {title: 'File has been saved!'},
          {timeout: 5000}
        )}
        ///- end highlight -///
      >
        Save file
      </Button>
    );
  }
  ```

  ```tsx render hideImports type="tailwind"
  "use client";
  import {queue} from 'tailwind-starter/Toast';
  import {Button} from 'tailwind-starter/Button';

  function Example() {
    return (
      <Button
        ///- begin highlight -///
        onPress={() => queue.add(
          {title: 'File has been saved!'},
          {timeout: 5000}
        )}
        ///- end highlight -///
      >
        Save file
      </Button>
    );
  }
  ```

</ExampleSwitcher>

<InlineAlert variant="notice">
  <Heading>Accessibility</Heading>
  <Content>Only auto-dismiss toasts when the information is not critical, or may be found elsewhere. Some users may require additional time to read toasts, and screen zoom users may miss them entirely.</Content>
</InlineAlert>

### Programmatic dismissal

Toasts can be programmatically dismissed using the key returned from `queue.add()`. This is useful when a toast becomes irrelevant before the user manually closes it.

<ExampleSwitcher>
  ```tsx render hideImports type="vanilla"
  "use client";
  import {queue} from 'vanilla-starter/Toast';
  import {Button} from 'vanilla-starter/Button';
  import {useState} from 'react';

  function Example() {
    let [toastKey, setToastKey] = useState(null);

    return (
      <Button
        ///- begin highlight -///
        onPress={() => {
          if (!toastKey) {
            setToastKey(queue.add(
              {title: 'Processing...'},
              {onClose: () => setToastKey(null)}
            ));
          } else {
            queue.close(toastKey);
          }
        }}
        ///- end highlight -///
      >
        {toastKey ? 'Cancel' : 'Process'}
      </Button>
    );
  }
  ```

  ```tsx render hideImports type="tailwind"
  "use client";
  import {queue} from 'tailwind-starter/Toast';
  import {Button} from 'tailwind-starter/Button';
  import {useState} from 'react';

  function Example() {
    let [toastKey, setToastKey] = useState(null);

    return (
      <Button
        ///- begin highlight -///
        onPress={() => {
          if (!toastKey) {
            setToastKey(queue.add(
              {title: 'Processing...'},
              {onClose: () => setToastKey(null)}
            ));
          } else {
            queue.close(toastKey);
          }
        }}
        ///- end highlight -///
      >
        {toastKey ? 'Cancel' : 'Process'}
      </Button>
    );
  }
  ```

</ExampleSwitcher>

## Accessibility

Toast regions are [landmark regions](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/) that can be navigated using <Keyboard>F6</Keyboard> to move forward and <Keyboard>Shift</Keyboard> + <Keyboard>F6</Keyboard> to move backward. This provides an easy way for keyboard users to jump to toasts from anywhere in the app.

When a toast is closed, focus moves to the next toast if any. When the last toast is closed, focus is restored to where it was before.

## API

<Anatomy role="img" aria-label="Toast anatomy diagram, showing the toast's title and close button within the toast region." />

```tsx links={{ToastRegion: '#toastregion', Toast: '#toast', ToastContent: '#toastcontent', ToastQueue: '#toastqueue', Button: 'Button'}}
<ToastRegion>
  {({toast}) => (
    <Toast toast={toast}>
      <ToastContent>
        <Text slot="title" />
        <Text slot="description" />
      </ToastContent>
      <Button slot="close" />
    </Toast>
  )}
</ToastRegion>
```

### ToastRegion

<PropTable component={docs.exports.UNSTABLE_ToastRegion} links={docs.links} showDescription />

### Toast

<PropTable component={docs.exports.UNSTABLE_Toast} links={docs.links} showDescription />

### ToastContent

`<ToastContent>` renders the main content of a toast, including the title and description slots. It accepts all HTML attributes.

### ToastQueue

A `ToastQueue` manages the state for a `<ToastRegion>`. The state is stored outside React so you can trigger toasts from anywhere in your application.

<ClassAPI links={docs.links} class={docs.exports.UNSTABLE_ToastQueue} />
